<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.13"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Asynchronous Notification</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
</script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectlogo"><img alt="Logo" src="kvaser.gif"/></td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.13 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
</script>
<div id="main-nav"></div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('page_user_guide_send_recv_asynch_not.html','');});
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="header">
  <div class="headertitle">
<div class="title">Asynchronous Notification </div>  </div>
</div><!--header-->
<div class="contents">
<div class="toc"><h3>Table of Contents</h3>
<ul><li class="level1"><a href="#section_user_guide_send_recv_asynch">Asynchronous Notifications</a><ul><li class="level2"><a href="#section_user_guide_send_recv_asynch_receive">Receive Events</a></li>
<li class="level2"><a href="#section_user_guide_send_recv_asynch_transmit">Transmit Events</a></li>
<li class="level2"><a href="#section_user_guide_send_recv_asynch_status">Status Events</a></li>
<li class="level2"><a href="#section_user_guide_send_recv_asynch_error">Error Events</a></li>
</ul>
</li>
<li class="level1"><a href="#section_user_guide_send_recv_asynch_callback">Receiving Using Callback Function</a></li>
</ul>
</div>
<div class="textblock"><h1><a class="anchor" id="section_user_guide_send_recv_asynch"></a>
Asynchronous Notifications</h1>
<p>You can receive an asynchronous notification when certain events occur in CANlib, for example, when a message arrives or when the CAN controller goes "error passive" due to bus errors. Use <a class="el" href="group___c_a_n.html#gaa5dd0f277c7059169055321fbda87486">canSetNotify()</a> to tell CANlib what events you want notifications for. The different kinds of events are described below.</p>
<p>When the specified kind of event occur, the callback function that was specified in the call to <a class="el" href="group___c_a_n.html#gaa5dd0f277c7059169055321fbda87486">canSetNotify()</a> is called. The callback receives a pointer to a <a class="el" href="structcan_notify_data.html">canNotifyData</a> struct; its contents vary depending on the kind of event and is described below.</p>
<p><b>Example</b> </p><div class="fragment"><div class="line">hnd = <a class="code" href="group___c_a_n.html#gac377d182232fb4ec2fed881c2b9ab300">canOpenChannel</a>(...);</div><div class="line">...</div><div class="line">stat = <a class="code" href="group___c_a_n.html#gaa5dd0f277c7059169055321fbda87486">canSetNotify</a>(hnd, wndHandle, <a class="code" href="canstat_8h.html#af0b2b8979177da5f9c875f584f9c7d9c">canNOTIFY_RX</a>);</div></div><!-- fragment --><p>When a CAN message is received and the receive queue is empty, a <code>WM__CANLIB</code> message will be sent to the window whose handle is wndHandle. The <code>WM__CANLIB</code> message will have</p>
<div class="fragment"><div class="line">wParam == hnd</div><div class="line">HIWORD(lParam) == 0</div><div class="line">LOWORD(lParam) == <a class="code" href="canstat_8h.html#af5f5917ba5476570815747b960e26ba6">canEVENT_RX</a></div></div><!-- fragment --><p>In the routine that handles <code>WM__CANLIB</code>, you should call <a class="el" href="group___c_a_n.html#ga157d49a9343dea68ac953145e02266d8">canRead()</a> repeatedly, using the handle found in <em>wParam</em>, until it returns <a class="el" href="canstat_8h.html#a52b5e5c71832b0bd3c6a5b1fd48583e7a734089f351bc421c230bf8b6cd9b1e8e">canERR_NOMSG</a> or some other error code.</p>
<h2><a class="anchor" id="section_user_guide_send_recv_asynch_receive"></a>
Receive Events</h2>
<p>A receive event occurs when a CAN message arrives to a previously empty queue. In other words, there will be a receive event when the queue needs servicing but you will not receive an event for every received CAN message. The <a class="el" href="structcan_notify_data.html">canNotifyData</a> eventType field will be set to <a class="el" href="canstat_8h.html#af5f5917ba5476570815747b960e26ba6">canEVENT_RX</a>, and the <code>rx.id</code> and r<code>x.time</code> fields will be set to the message ID and timestamp.</p>
<h2><a class="anchor" id="section_user_guide_send_recv_asynch_transmit"></a>
Transmit Events</h2>
<p>A transmit event occurs whenever a CAN message has been transmitted. The <a class="el" href="structcan_notify_data.html">canNotifyData</a> eventType field will be set to <a class="el" href="canstat_8h.html#a21669303d34190235f63303deae6b248">canEVENT_TX</a>, and the <code>tx.id</code> and <code>tx.time</code> fields will be set to the message ID and timestamp.</p>
<h2><a class="anchor" id="section_user_guide_send_recv_asynch_status"></a>
Status Events</h2>
<p>A status event occurs when the bus status of the CAN controller has changed, for example, if the controller goes "error passive" due to bus errors. The <a class="el" href="structcan_notify_data.html">canNotifyData</a> eventType field will be set to <a class="el" href="canstat_8h.html#a0c59f7bbcb5cceaefe0d1d5915e8b4fc">canEVENT_STATUS</a>. The <code>info.status.busStatus</code>, <code>info.status.txErrorCounter</code>, <code>info.status.rxErrorCounter</code>, and info.status.time field will be set to status information.</p>
<h2><a class="anchor" id="section_user_guide_send_recv_asynch_error"></a>
Error Events</h2>
<p>An error frame has been received. The <a class="el" href="structcan_notify_data.html">canNotifyData</a> eventType field will be set to <a class="el" href="canstat_8h.html#a5a6431078d49d8f7cc36c6313db44406">canEVENT_ERROR</a>, and the <code>info.busErr.time</code> field will be set to the error timestamp.</p>
<h1><a class="anchor" id="section_user_guide_send_recv_asynch_callback"></a>
Receiving Using Callback Function</h1>
<p>You can call the <a class="el" href="group__can__general.html#ga99976c5b8e2c534b27bf9ec2e715d8d3">kvSetNotifyCallback()</a> function to register a callback that is called by CANlib when certain events occur. The callback function is called in the context of a high-priority thread created by CANlib. You should be careful not to perform any time consuming tasks within the callback function, and you must also arrange for the synchronization between the callback function and the rest of your code. </p>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- HTML footer for doxygen 1.8.13-->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="navelem"><a class="el" href="page_canlib.html">CAN bus API (CANlib)</a></li>
    <li class="footer"> (canlib 5.38) Tue Feb 15 2022</li>
  </ul>
</div>
</body>
</html>
